.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "GDALADDO" "1" "Feb 08, 2024" "" "GDAL"
.SH NAME
gdaladdo \- Builds or rebuilds overview images.
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gdaladdo [\-\-help] [\-\-help\-general]
         [\-r {nearest|average|rms|gauss|cubic|cubicspline|lanczos|average_mp|average_magphase|mode}]
         [\-ro] [\-clean] [\-q] [\-oo <NAME>=<VALUE>]... [\-minsize <val>]
         [\-\-partial\-refresh\-from\-source\-timestamp]
         [\-\-partial\-refresh\-from\-projwin <ulx> <uly> <lrx> <lry>]
         [\-\-partial\-refresh\-from\-source\-extent <filename1>[,<filenameN>]...]
         <filename> [<levels>]...
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
The \fBgdaladdo\fP utility can be used to build or rebuild overview images for
most supported file formats with one of several downsampling algorithms.
.INDENT 0.0
.TP
.B \-\-help
Show this help message and exit
.UNINDENT
.INDENT 0.0
.TP
.B \-\-help\-general
Gives a brief usage message for the generic GDAL commandline options and exit.
.UNINDENT
.INDENT 0.0
.TP
.B \-r {nearest|average|rms|gauss|cubic|cubicspline|lanczos|average_magphase|mode}
Select a resampling algorithm.
.sp
\fBnearest\fP applies a nearest neighbour (simple sampling) resampler (default)
.sp
\fBaverage\fP computes the average of all non\-NODATA contributing pixels. Starting with GDAL 3.1, this is a weighted average taking into account properly the weight of source pixels not contributing fully to the target pixel.
.sp
\fBrms\fP computes the root mean squared / quadratic mean of all non\-NODATA contributing pixels (GDAL >= 3.3)
.sp
\fBbilinear\fP applies a bilinear convolution kernel.
.sp
\fBgauss\fP applies a Gaussian kernel before computing the overview,
which can lead to better results than simple averaging in e.g case of sharp edges
with high contrast or noisy patterns. The advised level values should be 2, 4, 8, ...
so that a 3x3 resampling Gaussian kernel is selected.
.sp
\fBcubic\fP applies a cubic convolution kernel.
.sp
\fBcubicspline\fP applies a B\-Spline convolution kernel.
.sp
\fBlanczos\fP applies a Lanczos windowed sinc convolution kernel.
.sp
\fBaverage_magphase\fP averages complex data in mag/phase space.
.sp
\fBmode\fP selects the value which appears most often of all the sampled points.
.UNINDENT
.INDENT 0.0
.TP
.B \-b <band>
Select an input band \fBband\fP for overview generation. Band numbering
starts from 1. Multiple \fI\%\-b\fP switches may be used to select a set
of input bands to generate overviews.
.UNINDENT
.INDENT 0.0
.TP
.B \-ro
open the dataset in read\-only mode, in order to generate external overview
(for GeoTIFF especially).
.UNINDENT
.INDENT 0.0
.TP
.B \-clean
remove all overviews.
.UNINDENT
.INDENT 0.0
.TP
.B \-oo <NAME>=<VALUE>
Dataset open option (format specific)
.UNINDENT
.INDENT 0.0
.TP
.B \-minsize <val>
Maximum width or height of the smallest overview level. Only taken into
account if explicit levels are not specified. Defaults to 256.
.sp
New in version 2.3.

.UNINDENT
.INDENT 0.0
.TP
.B \-\-partial\-refresh\-from\-source\-timestamp
New in version 3.8.

.sp
This option performs a partial refresh of existing overviews, when <filename>
is a VRT file with an external overview.
It checks the modification timestamp of all the sources of the VRT
and regenerate the overview for areas corresponding to sources whose
timestamp is more recent than the external overview of the VRT.
By default all existing overview levels will be refreshed, unless explicit
levels are specified.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-partial\-refresh\-from\-projwin <ulx> <uly> <lrx> <lry>
New in version 3.8.

.sp
This option performs a partial refresh of existing overviews, in the region
of interest specified by georeference coordinates where <ulx> is the X value
of the upper left corner, <uly> is the Y value of the upper left corner,
<lrx> is the X value of the lower right corner and <lry> is the Y value of
the lower right corner.
By default all existing overview levels will be refreshed, unless explicit
levels are specified.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-partial\-refresh\-from\-source\-extent <filename1>[,<filenameN>]...
New in version 3.8.

.sp
This option performs a partial refresh of existing overviews, in the region
of interest specified by one or several filenames (names separated by comma).
Note that the filenames are only used to determine the regions of interest
to refresh. The reference source pixels are the one of the main dataset.
By default all existing overview levels will be refreshed, unless explicit
levels are specified.
.UNINDENT
.INDENT 0.0
.TP
.B <filename>
The file to build overviews for (or whose overviews must be removed).
.UNINDENT
.INDENT 0.0
.TP
.B <levels>
A list of integral overview levels to build. Ignored with \fI\%\-clean\fP option.
.sp
New in version 2.3: levels are no longer required to build overviews.
In which case, appropriate overview power\-of\-two factors will be selected
until the smallest overview is smaller than the value of the \-minsize switch.

.UNINDENT
.sp
gdaladdo will honour properly NODATA_VALUES tuples (special dataset metadata) so
that only a given RGB triplet (in case of a RGB image) will be considered as the
nodata value and not each value of the triplet independently per band.
.sp
Selecting a level value like \fB2\fP causes an overview level that is 1/2
the resolution (in each dimension) of the base layer to be computed.  If
the file has existing overview levels at a level selected, those levels will
be recomputed and rewritten in place.
.sp
For internal GeoTIFF overviews (or external overviews in GeoTIFF format), note
that \-clean does not shrink the file. A later run of gdaladdo with overview levels
will cause the file to be expanded, rather than reusing the space of the previously
deleted overviews. If you just want to change the resampling method on a file that
already has overviews computed, you don\(aqt need to clean the existing overviews.
.sp
Some format drivers do not support overviews at all.  Many format drivers
store overviews in a secondary file with the extension .ovr that is actually
in TIFF format.  By default, the GeoTIFF driver stores overviews internally to the file
operated on (if it is writable), unless the \-ro flag is specified.
.sp
Most drivers also support an alternate overview format using Erdas Imagine
format.  To trigger this use the \fI\%USE_RRD=YES\fP configuration option.  This will
place the overviews in an associated .aux file suitable for direct use with
Imagine or ArcGIS as well as GDAL applications.  (e.g. \-\-config USE_RRD YES)
.SH EXTERNAL OVERVIEWS IN GEOTIFF FORMAT
.sp
External overviews created in TIFF format may be compressed using the \fI\%COMPRESS_OVERVIEW\fP
configuration option.  All compression methods, supported by the GeoTIFF
driver, are available here. (e.g. \fB\-\-config COMPRESS_OVERVIEW DEFLATE\fP).
The photometric interpretation can be set with the \fI\%PHOTOMETRIC_OVERVIEW\fP
=RGB/YCBCR/... configuration option,
and the interleaving with the \fI\%INTERLEAVE_OVERVIEW\fP =PIXEL/BAND configuration option.
.sp
Since GDAL 3.6, \fI\%COMPRESS_OVERVIEW\fP and \fI\%INTERLEAVE_OVERVIEW\fP
are honoured when creating internal overviews of TIFF files.
.sp
For JPEG compressed external and internal overviews, the JPEG quality can be set with
\fB\-\-config JPEG_QUALITY_OVERVIEW value\fP\&.
.sp
For WEBP compressed external and internal overviews, the WEBP quality level can be set with
\fB\-\-config WEBP_LEVEL_OVERVIEW value\fP\&. If not set, will default to 75.
.sp
For WEBP compressed external and internal overviews, the WEBP lossless/lossy switch can be set with
\fB\-\-config WEBP_LOSSLESS_OVERVIEW value\fP\&. If not set, will default to NO (lossy). Added in GDAL 3.6.0
.sp
For LERC compressed external and internal overviews, the max error threshold can be set with
\fB\-\-config MAX_Z_ERROR_OVERVIEW value\fP\&. If not set, will default to 0 (lossless). Added in GDAL 3.4.1
.sp
For DEFLATE or LERC_DEFLATE compressed external and internal overviews, the compression level can be set with
\fB\-\-config ZLEVEL_OVERVIEW value\fP\&. If not set, will default to 6. Added in GDAL 3.4.1
.sp
For ZSTD or LERC_ZSTD compressed external and internal overviews, the compression level can be set with
\fB\-\-config ZSTD_LEVEL_OVERVIEW value\fP\&. If not set, will default to 9. Added in GDAL 3.4.1
.sp
For LZW, ZSTD or DEFLATE compressed external overviews, the predictor value can be set
with \fB\-\-config PREDICTOR_OVERVIEW 1|2|3\fP\&.
.sp
To produce the smallest possible JPEG\-In\-TIFF overviews, you should use:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-\-config COMPRESS_OVERVIEW JPEG \-\-config PHOTOMETRIC_OVERVIEW YCBCR \-\-config INTERLEAVE_OVERVIEW PIXEL
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
External overviews can be created in the BigTIFF format by using
the \fI\%BIGTIFF_OVERVIEW\fP configuration option:
\fB\-\-config BIGTIFF_OVERVIEW {IF_NEEDED|IF_SAFER|YES|NO}\fP\&.
.sp
The default value is IF_SAFER starting with GDAL 2.3.0 (previously was IF_NEEDED).
The behavior of this option is exactly the same as the BIGTIFF creation option
documented in the GeoTIFF driver documentation.
.INDENT 0.0
.IP \(bu 2
YES forces BigTIFF.
.IP \(bu 2
NO forces classic TIFF.
.IP \(bu 2
IF_NEEDED will only create a BigTIFF if it is clearly needed (uncompressed,
and overviews larger than 4GB).
.IP \(bu 2
IF_SAFER will create BigTIFF if the resulting file \fImight\fP exceed 4GB.
.UNINDENT
.sp
Sparse GeoTIFF overview files (that is tiles which are omitted if all their pixels are
at the nodata value, when there\(aqs one, or at 0 otherwise) can be obtained with
\fB\-\-config SPARSE_OK_OVERVIEW ON\fP\&. Added in GDAL 3.4.1
.sp
See the documentation of the \fI\%GTiff \-\- GeoTIFF File Format\fP driver for further explanations on all those options.
.SH SETTING BLOCKSIZE IN GEOTIFF OVERVIEWS
.sp
\fB\-\-config GDAL_TIFF_OVR_BLOCKSIZE <size>\fP
.sp
Example: \fB\-\-config GDAL_TIFF_OVR_BLOCKSIZE 256\fP
.sp
Default value is 128, or starting with GDAL 3.1, if creating overviews on a tiled GeoTIFF file, the tile size of the full resolution image.
Note: without this setting, the file can have the full resolution image with a blocksize different from overviews blocksize.(e.g. full resolution image at blocksize 256, overviews at blocksize 128)
.SH NODATA / SOURCE VALIDITY MASK HANDLING DURING RESAMPLING
.sp
Invalid values in source pixels, either identified through a nodata value
metadata set on the source band, a mask band, an alpha band will not be used
during resampling.
.sp
The details of how it is taken into account depends on the resampling kernel:
.INDENT 0.0
.IP \(bu 2
for nearest resampling, for each target pixel, one of the potential contributing
source pixels is selected (in an implementation specific way). Its value is used
as it, be it valid or invalid.
.IP \(bu 2
for bilinear, cubic, cubicspline and lanczos, for each target pixel, the weights
of contributing source pixels is set to zero to ignore them when they are masked.
There is an extra specificity for cubic: given that some of the weights in the
kernel are negative, such strategy could lead to strong overshoot/undershoot
when there is an alternance of valid and invalid pixels. Consequently, if any
of the horizontal or vertical direction, if the maximum number of valid source
pixels in each dimension is less than the radius of the resampling kernel,
the target pixel is considered as nodata.
.IP \(bu 2
for the other resampling methods, source pixels contributing to the target pixel
are ignored if masked. Only the valid ones are taken into account. If there are
none, the target pixel is considered as nodata.
.UNINDENT
.SH MULTITHREADING
.sp
New in version 3.2.

.sp
The \fI\%GDAL_NUM_THREADS\fP configuration option can be set to
\fBALL_CPUS\fP or a integer value to specify the number of threads to use for
overview computation.
.SH C API
.sp
Functionality of this utility can be done from C with \fI\%GDALBuildOverviews()\fP\&.
.SH EXAMPLES
.sp
Create overviews, embedded in the supplied TIFF file, with automatic computation
of levels (GDAL 2.3 or later)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gdaladdo \-r average abc.tif
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Create overviews, embedded in the supplied TIFF file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gdaladdo \-r average abc.tif 2 4 8 16
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Create an external compressed GeoTIFF overview file from the ERDAS .IMG file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gdaladdo \-ro \-\-config COMPRESS_OVERVIEW DEFLATE erdas.img 2 4 8 16
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Create an external JPEG\-compressed GeoTIFF overview file from a 3\-band RGB dataset
(if the dataset is a writable GeoTIFF, you also need to add the \-ro option to
force the generation of external overview):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gdaladdo \-\-config COMPRESS_OVERVIEW JPEG \-\-config PHOTOMETRIC_OVERVIEW YCBCR
         \-\-config INTERLEAVE_OVERVIEW PIXEL rgb_dataset.ext 2 4 8 16
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Create an Erdas Imagine format overviews for the indicated JPEG file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gdaladdo \-\-config USE_RRD YES airphoto.jpg 3 9 27 81
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Create overviews for a specific subdataset, like for example one of potentially many raster layers in a GeoPackage (the \(dqfilename\(dq parameter must be driver prefix, filename and subdataset name, like e.g. shown by gdalinfo):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gdaladdo GPKG:file.gpkg:layer
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Refresh overviews of a VRT file, for sources that have been modified after the
\&.vrt.ovr generation:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gdalbuildvrt my.vrt tile1.tif tile2.tif                          # create VRT
gdaladdo \-r cubic my.vrt                                         # initial overview generation
touch tile1.tif                                                  # simulate update of one of the source tiles
gdaladdo \-\-partial\-refresh\-from\-source\-timestamp \-r cubic my.vrt # refresh overviews
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Refresh overviews of a TIFF file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gdalwarp \-overwrite tile1.tif tile2.tif mosaic.tif                      # create mosaic
gdaladdo \-r cubic mosaic.tif                                            # initial overview generation
touch tile1.tif                                                         # simulate update of one of the source tiles
gdalwarp tile1.tif mosaic.tif                                           # update mosaic
gdaladdo \-\-partial\-refresh\-from\-source\-extent tile1.tif \-r cubic my.vrt # refresh overviews
.ft P
.fi
.UNINDENT
.UNINDENT
.SH AUTHOR
Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer <silke@intevation.de>
.SH COPYRIGHT
1998-2024
.\" Generated by docutils manpage writer.
.
